home *** CD-ROM | disk | FTP | other *** search
/ Apple WWDC 1996 / WWDC96_1996 (CD).toast / Technology Materials / MacApp Release 10 / MacApp Release 10 - HD Ready / Libraries / Mail / Includes / UMailable.h < prev    next >
Encoding:
Text File  |  1996-04-03  |  12.4 KB  |  401 lines  |  [TEXT/MPS ]
  1. // UMailable.h
  2. // Copyright © 1984-96 by Apple Computer, Inc. All rights reserved.
  3.  
  4. #ifndef __UMAILABLE__
  5. #define __UMAILABLE__
  6.  
  7. #if qPowerTalk
  8.  
  9. // MacApp
  10.  
  11. #ifndef __MACAPPTYPES__
  12. #include "MacAppTypes.h"
  13. #endif
  14.  
  15. #ifndef __UCLASSDESC__
  16. #include "UClassDesc.h"
  17. #endif
  18.  
  19. #ifndef __UCOMMAND__
  20. #include "UCommand.h"
  21. #endif
  22.  
  23. // Toolbox
  24.  
  25. #ifndef __APPLEEVENTS__
  26. #include <AppleEvents.h>
  27. #endif
  28.  
  29. #ifndef    __OCE__
  30. #include <OCE.h>
  31. #endif
  32.  
  33. #ifndef __OCEAUTHDIR__
  34. #include <OCEAuthDir.h>
  35. #endif
  36.  
  37. //----------------------------------------------------------------------------------------
  38. // Forward and external class declarations. 
  39. //----------------------------------------------------------------------------------------
  40.  
  41. class CAEDesc;
  42. class MScriptableObject;
  43. class TAppleEvent;
  44. class TDocument;
  45. class TLetter;
  46. class TToolboxEvent;
  47.  
  48. // For decodeing phone number info stored in DSSpecs
  49. struct PhoneNumberInfo
  50. {
  51.     short fSubType;
  52.     CStr31 fCountryCode;
  53.     CStr31 fAreaCode;
  54.     CStr31 fPhoneNumber;
  55.     CStr31 fPostFix;
  56.     CStr255 fDirectDial;
  57. };
  58.  
  59. //----------------------------------------------------------------------------------------
  60. // CDSSpec represents an AOCE DSSpec structure. DSSpecs are used to represent most objects
  61. // in AOCE including Catalogs, Catalog nodes, Catalog records, and mail addresses.
  62. // The DSSpec data is usually resides in a packed format, the PackedDSSpec. However, in
  63. // order to do much with it, the data needs to be unpacked into several other AOCE structures.
  64. // CDSSpec keeps the data packed in fPackedDSSpec but handles unpacking it when needed.
  65. // Only when the data is unpacked are the other CDSSpec fields valid. Unless you change the data
  66. // you don't need to pack it again when you are done.
  67. // CDSSpec owns the packed data in its fPackedDSSpec pointer. It will make a copy of the data
  68. // you pass its constructor and will dispose of its copy when deleted.
  69. //----------------------------------------------------------------------------------------
  70.  
  71. class CDSSpec
  72. {
  73. public:
  74.  
  75.     PackedDSSpecPtr fPackedDSSpec;
  76.     DSSpec fDSSpec;
  77.     RecordID fRecordID;
  78.     RLI fRLI;
  79.     Boolean fUnpacked;
  80.  
  81.     CDSSpec();
  82.         // Initializes a CDSSpec.
  83.         
  84.     CDSSpec(PackedDSSpecPtr aPackedDSSpec);
  85.         // Initializes a CDSSpec using a PackedDSSpecPtr. A copy of the data is made and unpacked.
  86.  
  87.     CDSSpec(const CAEDesc& anAEDesc);
  88.         // Initializes a CDSSpec using a CAEDesc. A copy of the data is made and unpacked.
  89.  
  90.     ~CDSSpec();
  91.         // Disposes of the data in fPackedDSSpec.
  92.  
  93.     Boolean Unpack();
  94.         // Unpacked the data in fPackedDSSpec into the fDSSpec, fRecordID, and fRLI fields.
  95.  
  96.     void Pack();
  97.         // Takes whatever is in the fDSSpec, fRecordID, and fRLI fields and packs it into a new fPackedDSSpec.
  98.  
  99.     void GetPathName(CStr255& thePathName);
  100.         // If the DSSpec describes a catalog record, returns a path name to that record.
  101.  
  102.     void GetAEDesc(CAEDesc& theAEDesc);
  103.         // Puts a copy of the fPackedDSSpec data into an CAEDesc.
  104.  
  105.     // Handy conversions.
  106.  
  107.     inline StringPtr GetRecordName(){ return OCERToPString(this->fRecordID.local.recordName); };
  108.  
  109.     inline StringPtr GetDirectoryName(){ return OCERToPString((RStringPtr)this->fRLI.directoryName); };
  110.  
  111.     inline StringPtr GetRecordType(){ return OCERToPString(this->fRecordID.local.recordType); };
  112.  
  113.     OSType GetExtensionType();
  114.  
  115.     // Conversion from string to address formats.
  116.     // Addresses are formatted: record name<service name><catalog name>address value.
  117.     // The catalog name is omitted if the same as the directory name.
  118.     // Some examples:
  119.     // "Ken Ryall<AppleTalk>Ken's Mac@R&D Zone"
  120.     // "Tom Becker<Internet>twb@apple.com"
  121.     // "Janie Phillips<Pager><Century Paging>2568345"
  122.     // "Tom's Fax Machine<Fax Terminal>1-408-555-8989"
  123.     // "Paul Drake<PowerShare>Sales:Staff:East Coast"
  124.  
  125.     static Boolean GetDirectoryExtensionType(OSType myExtType, Boolean& isRString,
  126.                                              CStr255& dirSysName);
  127.         // Look up the extension type in the directory extension type table ('dxtt' resource).
  128.     
  129.     void AddressToString(CStr255& theString);
  130.         // Creates a string that describes this DSSpec.
  131.  
  132.     void StringToAddress(CStr255& theString);
  133.         // Parses a valid address string into a DSSpec.
  134.  
  135.     // Utilities for parsing address strings
  136.  
  137.     void ParsePowerShareAddress(CStr31& dsDirName,
  138.                                 CStr255& dsExtValue);
  139.         // Parses a path name to a catalog record and sets the fRLI to point to it.
  140.  
  141.     void ParseAppleTalkAddress(CStr255& dsExtValue);
  142.         // Parses the extension string into an AppleTalk EntityName.
  143.  
  144.     void ParseDirectDialupAddress(CStr255& dsExtValue);
  145.         // Parses a phone number string into a packed direct dial number.
  146.  
  147.     void ParseFaxSTFAddress(CStr31& dsRecName,
  148.                                 CStr255& dsExtValue);
  149.         // Parses a phone number string into a format for the STF fax PMSAM.
  150.  
  151.     void ParseRStringAddress(CStr255& dsExtValue);
  152.         // The default MSAM address format is an RString in the extensionValue.
  153.  
  154.     // Utilities for unpacking phone number info
  155.  
  156.     PhoneNumberInfo* UnpackDirectDialupInfo();
  157.  
  158.     PhoneNumberInfo* UnpackSTFFaxInfo();
  159.  
  160.     // Utilities for packing and unpacking strings
  161.  
  162.     static void PackString(Ptr& packIn,
  163.                            const CStr31& theStr);
  164.  
  165.     static void PackRString(Ptr& packIn,
  166.                             const CStr31& theStr);
  167.  
  168.     static void PackRString(Ptr& packIn,
  169.                             RStringPtr theStr);
  170.  
  171.     static StringPtr UnpackRString(Ptr& unpackFrom);
  172. };
  173.  
  174. //----------------------------------------------------------------------------------------
  175. // CCatalogs represents the top level of the catalog system. It will enumerate
  176. // through each catalog (AppleTalk, PowerShare, X.500, database etc) but not the
  177. // contents of the catalog.
  178. //----------------------------------------------------------------------------------------
  179.  
  180. class CCatalogs
  181. {
  182. public:
  183.  
  184.     DirectoryName fStartingDirectoryName;
  185.     DirDiscriminator fStartingDirDiscriminator;
  186.     ForEachDirectory fForEachDirectoryProc;
  187.     long fClientData;
  188.     Boolean fCatalogFound;
  189.     DirectoryNamePtr fDirectoryNameToFind;
  190.     DirDiscriminator fFoundDirDiscriminator;
  191.  
  192.     CCatalogs();
  193.  
  194.     void EnumerateCatalogs(OCEDirectoryKind catalogType,
  195.                            ForEachDirectory actionProc);
  196.         // Calls the actionProc for each catalog.
  197.         
  198.     Boolean FindCatalogByName(DirectoryNamePtr theCatalogName,
  199.                               OCEDirectoryKind catalogType,
  200.                               DirDiscriminator& discriminator);
  201.         // Return TRUE if there is a catalog of the requested name and type.
  202.  
  203.     static Boolean FindCatalogByNameProc(long clientData,
  204.                                          const DirectoryName* dirName,
  205.                                          const DirDiscriminator* discriminator,
  206.                                          DirGestalt features);
  207.  
  208.     static Boolean EachCatalogGlue(long clientData,
  209.                                    const DirectoryName* dirName,
  210.                                    const DirDiscriminator* discriminator,
  211.                                    DirGestalt features);
  212.  
  213. };
  214.  
  215.  
  216. //----------------------------------------------------------------------------------------
  217. // MMailing: Adds mailing capability to an application. 
  218. //----------------------------------------------------------------------------------------
  219.  
  220. class MMailing
  221. {
  222.     MA_DECLARE_CLASS;
  223.     
  224. public:
  225.     
  226.     OSType fMainLetterFileType;                    // principal file type this application
  227.                                                 // uses for letters.
  228.     
  229.     MMailing();
  230.         // Constructor
  231.  
  232.     virtual OSErr GetAOCEIdentity(AuthIdentity& theIdentity,
  233.                                   Boolean allowInteraction);
  234.         // Get the local AOCE identity
  235.  
  236.     virtual Boolean DoMailerEvent(TToolboxEvent* event);
  237.         // Passes events to the standard mail package. Returns true if the SMP handled the event.
  238.  
  239.     virtual void OpenOldLetters(CommandNumber itsOpenCommand,
  240.                              const CAEDesc& letterList);
  241.         // Similar to OpenOld but handles a list of letter specs from the mail system.
  242.  
  243.     virtual TDocument* FindLetter(Handle itsSpec);
  244.         // Given a handle to a LetterSpecifier, if that letter is already opened, returns the TDocument.
  245.         // Otherwise returns NULL.
  246.  
  247.     virtual Boolean CanOpenLetter(CommandNumber itsCommandNumber,
  248.                                   Handle itsSpec);
  249.         // Given a handle to a LetterSpecifier returns if you want to open this letter.
  250.         // Default return TRUE.
  251.  
  252.     virtual Boolean IsLetterFileType(OSType theFileType);
  253.         // Return true if theFileType is a letter format this application can open.
  254.  
  255.     virtual void DoOpenNextLetter(CommandNumber aCommandNumber);
  256.         // Open the next unread letter in the mailbox.
  257.  
  258.     // Data type conversion routines.
  259.  
  260.     virtual OSErr TextToDSSpec(const void *textPtr, Size textSize, CAEDesc &result); 
  261.  
  262.     virtual OSErr DSSpecToText(const void *dataPtr, Size dataSize, CAEDesc &result);
  263.  
  264.     // Glue routines
  265.     
  266.     static pascal OSErr TextToDSSpecGlue(DescType typeCode, const void *dataPtr, Size dataSize, DescType toType, long handlerRefcon, AEDesc *result);
  267.  
  268.     static pascal OSErr DSSpecToTextGlue(DescType typeCode, const void *dataPtr, Size dataSize, DescType toType, long handlerRefcon, AEDesc *result);
  269. };
  270.  
  271. //----------------------------------------------------------------------------------------
  272. // MMailable: Corresponds to a Finder document. Manages mail data in files and in main
  273. // memory.
  274. //----------------------------------------------------------------------------------------
  275.  
  276. class MMailable
  277. {
  278.     MA_DECLARE_CLASS;
  279.     
  280. public:
  281.     TLetter* fLetter;                        // The mailer enclosing this document. 
  282.     
  283.     OSType fMailCreator;                    // Creator ID to use for letters. Defaults to AppleMail.
  284.  
  285.     OSType fMailType;                        // Type ID to use for letters. Defaults to fMainLetterFileType.
  286.  
  287.     unsigned long fSendFormats;                // Actually an SMPSendFormatMask
  288.     
  289.     
  290.     MMailable();
  291.         // Constructor
  292.         
  293.     virtual ~MMailable();
  294.         // Destructor.
  295.  
  296.  
  297.     virtual void AddNativeMailContent(Boolean& okToSend);
  298.         // Called to put the document's content into the letter in the document's
  299.         // native format. Default glues to the letter's equivalent function. 
  300.  
  301.     virtual void AddSnapshotMailContent(Boolean& okToSend);
  302.         // Called to create a snapshot of the document and add this to the letter.
  303.         // Default glues to the letter's equivalent function. 
  304.  
  305.     virtual void AddStandardMailContent(Boolean& okToSend);
  306.         // Called to put the document's content into the letter in the standard mail
  307.         // format. Default glues to the letter's equivalent function. 
  308.  
  309.     long CountContainedMailers();
  310.  
  311.     void DoAECreateMailer(TAppleEvent* message,
  312.                           TAppleEvent* reply);
  313.         // Adds a mailer to this document.
  314.  
  315.     virtual void DoAECreateReply(TAppleEvent* message,
  316.                                  TAppleEvent* reply);
  317.         // Glue to the letter's function.
  318.  
  319.     void DoAESend(TAppleEvent* message,
  320.                   TAppleEvent* reply);
  321.         // Handles the send event
  322.  
  323.     virtual Boolean DoMailMenuCommand(CommandNumber aCommandNumber);
  324.         // Handles the default menu commands associated with a mailable document.
  325.  
  326.     virtual void DoMakeLetter();
  327.         // Create the enclosing letter object. Override to make more capable letters. 
  328.     
  329.     virtual void DoSetupMailMenus();
  330.         // Set up the mail menu. 
  331.  
  332.     virtual TDocument* FindLetter(Handle itsSpec);
  333.         // True is this letter is already open.
  334.  
  335.     MScriptableObject* GetIndContainedMailer(long index);
  336.  
  337.     virtual unsigned long GetSendFormats();
  338.         // Returns the sending formats this document supports. Default returns
  339.         // fSendFormats, which is initialized to all three. 
  340.  
  341.     virtual Boolean HasMailer();
  342.         // Does this document have a mailer attached?
  343.  
  344.     virtual void ImageDocumentForLetter(Boolean inColor);
  345.         // Create an image of this document to be used as a letter snapshot.
  346.  
  347.     void LetterContentChanged();
  348.         // Tells the SMP that the document contents have changed. Called from 
  349.         // TDocument::Changed.
  350.  
  351.     virtual void MakeRoomForMailer(long amount, Boolean redraw);
  352.         // Adjust the views to make room for the mailer
  353.  
  354.     virtual void OpenLetter();
  355.         // Glue to the letter's function.
  356.  
  357.     virtual void ReadLetter(Boolean forPrinting);
  358.         // Glue to the letter's function.
  359.  
  360.     virtual Boolean ReadNativeMailContent();
  361.         // Called from OpenLetter to read the content in the document's native format.
  362.         // Default glues to the letter's function. 
  363.  
  364.     virtual Boolean ReadStandardMailContent();
  365.         // Called from OpenLetter to read the content in StandardMail Format.
  366.  
  367.     virtual Boolean ReadSnapshotMailContent();
  368.         // Called from OpenLetter to read the content in Snapshot Format.
  369.         
  370.     virtual void SetReplyContents(TDocument* replyToDoc);
  371.         // Called when this document is being created in reply to another. Override this
  372.         // to create any initial contents from the document being replied to.
  373. };
  374.  
  375. //----------------------------------------------------------------------------------------
  376. // TOpenNextLetterCommand: Open the next letter
  377. //----------------------------------------------------------------------------------------
  378.  
  379. class TOpenNextLetterCommand : public TCommand
  380. {
  381.     MA_DECLARE_CLASS;
  382.  
  383. public:
  384.  
  385.     TOpenNextLetterCommand();
  386.     
  387.     virtual ~TOpenNextLetterCommand();
  388.  
  389.     void IOpenNextLetterCommand(CommandNumber itsCommandNumber);
  390.     
  391.     virtual void DoIt();
  392.     
  393.     virtual TAppleEvent* MakeAppleEvent();
  394. };
  395.  
  396. extern MMailing* gMailing;
  397.  
  398. #endif // qPowerTalk
  399.  
  400. #endif // __UMAILABLE__
  401.